home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / applications / patch / phonepak_25_1.lha / PhonePak_2.5 / libsreq.library.readme < prev    next >
Encoding:
Text File  |  1994-05-18  |  11.5 KB  |  290 lines
  1.  
  2.  
  3.                        ReqLibrary, release 2.6
  4.                       -------------------------
  5.                     DATE Sat Mar  9 01:44:38 1991
  6.  
  7.  
  8.     The  req.library is a run time re-entrant library that is designed
  9. to  make  it  easier  for  programmers  to  use  powerful, easy to use
  10. requesters  for  communicating  with  users.   The  requester  library
  11. includes  such functions as a color requester, file requester, message
  12. display  requester  and many functions to make the creation of gadgets
  13. for your own custom requesters easier.
  14.  
  15.     Req.library  was  written  by  Colin  Fox (of Pyramyd Designs) and
  16. Bruce  Dawson  (of  CygnusSoft  Software).   Req.library  is  a freely
  17. distributable  library that may be used in commercial products without
  18. paying  any  royalties.  We encourage you to use the requester library
  19. in all of your programs, to make them easier to write, and to use.
  20.  
  21.     Req.library  is  not public domain.  The requester library and all
  22. documentation and example programs are all copyright 1989.
  23.  
  24.  
  25. //////////////////////////////////////////////////////////////////////
  26. Changes from req 2.5 to req 2.6
  27.  
  28. - You can now bring up the file requester from ARexx.
  29.  
  30. - Docs now in Autodoc format
  31.  
  32. - Bug fixed in font requester in Showoffreq
  33.  
  34. - es_SIZEOF changed to ess_SIZEOF in reqbase.i so it doesn't collide
  35.   with a new entry in intuition.i in 2.0
  36.  
  37. - Included spiffy new program: ReqMore! With source! This shows how
  38.   to use the RealTimeScroll() routine in req.library, and may also
  39.   serve as the basis of a tiny text editor for some enterprising programmer.
  40.  
  41. //////////////////////////////////////////////////////////////////////
  42. Changes from req 2.4 to req 2.5
  43.  
  44. - It was pointed out to me that Showoffreq.c and reqglue.asm haven't been
  45.   updated in a while, so here they are, updated.
  46.  
  47. - This version includes updates for both Lattice reqglue and Aztec reqglue.
  48.   There are 4 reqglues-
  49.          lreqgluenb.o  - for old Lattice or for Lattice compatable executables.
  50.                          the nb is for No Base relative addressing
  51.          lreqglue.o    - for new Lattice.
  52.  
  53.          areqglue.o    - old 3.6x Aztec
  54.  
  55.          areqglue50d.o - New 5.0d Aztec
  56.  
  57.  
  58. - I've also included the .fd file with this release, so if you wish to produce
  59.   a pragma file (or the equivalent), it's now easier.
  60.  
  61. //////////////////////////////////////////////////////////////////////
  62. Changes from req 2.3 to req 2.4
  63.  
  64. - Since Commodore saw fit to use our FileRequester name for their structure,
  65.   I have to change it to 'struct ReqFileRequester{};'
  66.  
  67. - And just to forstall any further problems, I changed ScrollStruct to
  68.   ReqScrollStruct.
  69.  
  70.   I know these are minor changes, but it had to be done.
  71.  
  72. //////////////////////////////////////////////////////////////////////
  73. Changes from req 2.2 to req 2.3
  74.  
  75. - It was found that the definition of ReqBase was as a *Library, not
  76.   as a *ReqLib, which would preclude getting to the various handy
  77.   pointers. This was fixed.
  78.  
  79. - Tune-ups have been made to the reqbase.? include files.
  80.  
  81. //////////////////////////////////////////////////////////////////////
  82.  
  83. Changes from req 1.2 to req 2.2
  84.  
  85. - All requesters handle fonts properly under Workbench 2.0
  86.  
  87. - The TextRequest now has a timeout. You supply the length of time, in
  88.   seconds, and the requester will CANCEL itself after that time.
  89.  
  90. - The GetLong requester now displays the Minimum and Maximum values
  91.   on the window.
  92.  
  93. - Format() has been renamed ReqFormat(), since there is now a DOS routine
  94.   called Format() that does something significantly different.
  95.  
  96. - ReqFormat() now returns the length of the formatted string, and it is
  97.   now safe to pass a null result buffer. This is useful if you wish to
  98.   allocate space for a string without needing a buffer first. Just run
  99.   ReqFormat() on the string once without a result buffer, and it will tell
  100.   you how long the string is. Then allocate the memory and do it again
  101.   with the result buffer.
  102.  
  103. - For future compatability, you must now put REQVERSION in all Version
  104.   structure fields. This begins now, as the Timeout routine looks at
  105.   the version.
  106.  
  107. -  RealTimeScroll  now  passes, as the 5th parameter (and in A0) the scroll
  108.    structure  to ScrollAndDraw (your routine).  This allows easier creation of
  109.    re-entrant   code  (you  don't  need  to  have  a  global  pointer  to  the
  110.    scrollstruct).
  111.  
  112. - ARexx interface
  113.    Many thanks to Steve Lyons for writing the rexx module for req.library.
  114.    To hook req.library in as an ARexx function library, you must execute the
  115.    following line:
  116.  
  117.     rxlib req.library -5 -60 2
  118.  
  119.    For example, my rxlib settings read as such:
  120.  
  121.     rxlib rexxmathlib.library  5 -30 0
  122.     rxlib rexxapclib.library   0 -30 0
  123.     rxlib rexxsupport.library -5 -30 0
  124.     rxlib rexxarplib.library -10 -30 0
  125.     rxlib req.library         -5 -60 2
  126.  
  127.  
  128.    Steve also wrote the following 4 ARexx <-> Req bindings:
  129.  
  130.  
  131. ------------------------------------------------------------------------------
  132. colourreq()
  133.  
  134.     This function requires no parameters, but you CAN pass the default colour
  135.     if you like.
  136.  
  137. ------------------------------------------------------------------------------
  138. intreq("Title",min,max)
  139.  
  140.     This function now displays the min and max values, so you know what's expected.
  141.  
  142. ------------------------------------------------------------------------------
  143. stringreq("Title","initial string",StringBufSize,VisibleSize)
  144.  
  145.     The only manditory paramter is Title.
  146.     There is no default initial string, so it would be blank
  147.     StringBufSize defaults to 255
  148.     VisibleSize defaults to 40
  149. ------------------------------------------------------------------------------
  150. textreq("Text body","Title","Cancel"," Ok ","Middle",timeout)
  151.  
  152.     Something new for req.library 2.2 is timeouts. Right now the only requester
  153.     that has timeouts is TextRequest(), but they will be added to the others.
  154.  
  155.     the timeout is in seconds. When the timeout expires, it returns FALSE.
  156.  
  157.     The only required parameter is the "Text Body"
  158.  
  159. ------------------------------------------------------------------------------
  160.  
  161.  
  162. //////////////////////////////////////////////////////////////////////
  163.  
  164.  
  165.  
  166.     Req.library  is  dedicated  to  the programmers who make the Amiga
  167. shine the way it was meant to.
  168.  
  169.  
  170. OverView:
  171.  
  172.     All  of  the  req.library functions that bring up requesters allow
  173. you two ways of specifying what screen you would like the requester to
  174. appear  on.  The first way is the more efficient way, because you only
  175. have  to set it up once and then it takes care of things automatially.
  176. There  is  a  field in all process structures called the pr_WindowPtr.
  177. This  pointer  is  used by DOS to decide where to put it's requesters.
  178. If  pr_WindowPtr  contains  a  zero,  requesters  go  on the workbench
  179. screen.  If it contains the address of a window, then requesters go on
  180. that  window's  screen.   If  it  contains a negative one, then no DOS
  181. requesters come up.  The req.library requesters all use this variable,
  182. if  they  are  called from a process .  However, if the pointer is -1,
  183. the req.library functions do still appear, on the workbench screen.
  184.  
  185.     The  second  way  was  put in mainly so that the requesters can be
  186. called from tasks.  Since a task does not have a process structure, it
  187. also  lacks a pr_WindowPtr.  Therefore, all of the requester functions
  188. which  can  be  used from a task (currently everything except the file
  189. requester) can be passed a window pointer, either as a parameter or as
  190. an  element in a structure.  Important:  This pointer takes precedence
  191. over  the  pr_WindowPtr  so  if  you  wish  the  requesters to use the
  192. pr_WindowPtr  you  must  zero  the window fields that the routines are
  193. expecting.   In  the case of fields in a structure this can be easy as
  194. long   as  you  make  sure  your  structure  defaults  to  being  zero
  195. everywhere.
  196.  
  197.     Setting  the  pr_WindowPtr is quite a simple matter.  All you have
  198. to do is do a FindTask((char *)0); which returns a pointer to your own
  199. task  and your own process (a task structure is the first element of a
  200. process  structure).   Then  you  simply  preserve  the  old  value of
  201. pr_WindowPtr (VERY IMPORTANT!!!) and put a window pointer into it.
  202.  
  203. eg:
  204.                 /* Find my task. */
  205.     myprocess = (struct Process *)FindTask((char *)0);
  206.     oldwindowptr = myprocess->pr_WindowPtr;
  207.     myprocess->pr_WindowPtr = window;
  208.  
  209. or:
  210.  
  211.     MOVE.L  4,A6
  212.     MOVE.L  #0,A1
  213.     SYS     FindTask    ;Find my task.
  214.     MOVE.L  D0,_myprocess
  215.     MOVE.L  D0,A0
  216.     MOVE.L  pr_WindowPtr(A0),_oldwindowptr
  217.     MOVE.L  _window,pr_WindowPtr(A0)
  218.  
  219.     Before your program exits it is VERY important that it restore the
  220. previous  value of pr_WindowPtr.  If you don't, then your program will
  221. work  in some situations, but will BLOW UP in others.  For example, if
  222. you  execute  (without  using the 'run' command) a program, which then
  223. sets  the  pr_WindowPtr  to  point at one of its windows and the exits
  224. without  restoring  it,  then  the  next time a DOS requester tries to
  225. appear...  BOOM!  The machine will probably crash as DOS tries to open
  226. a requester on a now closed screen.  Therefore, before leaving:
  227.  
  228.     myprocess->pr_WindowPtr = oldwindowptr;
  229.  
  230. or:
  231.  
  232.     MOVE.L  _myprocess,A0
  233.     MOVE.L  _oldwindowptr,pr_WindowPtr(A0)
  234.  
  235.  
  236.  
  237.     One  final  note.   The  pr_WindowPtr  field exists in the process
  238. structure.   This  means  that  a  task  does  not  have  this  field.
  239. Therefore,  if you want to call one of the requester library functions
  240. from  a  task,  you  will not be able to specify what screen you would
  241. like  the  requester  to  appear on by setting the pr_WindowPtr field.
  242. All  of  the  functions  that open requesters and can be called from a
  243. task  (the file requester/font requester is the only one that can't be
  244. called  froma task) have some other way of specifying which screen you
  245. would like them to open on.  They will have either have a field in the
  246. structure  which you must pass them or a parameter which can contain a
  247. window  pointer  to one of the windows on your custom screen.  If this
  248. pointer is non-zero then it overrides the pr_WindowPtr field.
  249.  
  250.  
  251.  
  252.  
  253.     By  opening the requester library, you not only gain access to all
  254. of  the functions documented below, but to some other goodies as well.
  255. Req.library   needs  and  therefore  opens  several  other  libraries,
  256. including  dos.library,  intuition.library,  graphics.library  and the
  257. console  device.   All  of  these  pointers  are  stored in the ReqLib
  258. structure  which  you  get a pointer to when you open the req.library.
  259. Therefore,  you  can  save  yourself  a little bit of code by grabbing
  260. these  fields  after opening the requester library.  The only thing to
  261. beware of is don't use these values after you have close the requester
  262. library,  because  at  that point there is no guarantee that they will
  263. still be valid.
  264.  
  265.     In  addition  to  these  libraries,  the Images pointer in the req
  266. library structure points to a set of ten small images (four arrows and
  267. six  letters  [R,  G,  B, H, S, V]) which have are guaranteed to be in
  268. chip  memory.  These can be used if your program requires this type of
  269. images.
  270.  
  271.  
  272.  
  273.  
  274.     One  thing to keep in mind when using the gadget creation routines
  275. is  that there isn't any way for us to check that you have passed us a
  276. pointer  to  the  correct size of buffer, so you _must_ make sure that
  277. you are allocating the right amount of memory.
  278.  
  279.  
  280.     The  two  glue files (lreqglue.o and areqglue.o) are for Lattice-C
  281. (now  SAS/C)  and  Aztec-C  respectively.   If  you  don't have direct
  282. library access, simply link in the appropriate glue file to access the
  283. library.
  284.  
  285.     With  the  new version of Lattice (5+) you can now jump to library
  286. routines directly, so there is no need for glue code.  You can do this
  287. with  Aztec  too,  apparently,  but  I don't have the pragma maker for
  288. Aztec.
  289.  
  290.